gh-156233: Fixing a couple of typos and a few code snippet errors in Python docs - #156475

error: The default argument to ParamSpec must be a list expression, ellipsis, or a ParamSpec  [misc]

error: The default argument to TypeVarTuple must be an Unpacked tuple  [misc]
error: TypeVarTuple "SimpleTypeVarTuple" is only valid with an unpack  [valid-type]

from typing import *

def overly_generic[
      SimpleTypeVar,
      TypeVarWithBound: int,
      TypeVarWithConstraints: (str, bytes), # originally used for return value type of callable param, I am proposing to leave that as is
      TypeVarWithDefault = int,
      *SimpleTypeVarTuple = *tuple[int, float], # match https://peps.python.org/pep-0646/
      # this is a valid format for declaring a ParamSpec as a generic type parameter
      **SimpleParamSpec = [str, bytearray], # same as `ParamSpec('SimpleParamSpec', default=[str, bytearray])`
   ](
      a: SimpleTypeVar,
      b: TypeVarWithBound,
      c: Callable[SimpleParamSpec, TypeVarWithConstraints], # not the same ordering as StanFromIreland's suggestion, but rather matches the type argument use in the original example; the Callable parameter return type IS the example for TypeVarWithConstraints, though I am fine to change the parameter (not type parameter) ordering however you want
      d: TypeVarWithDefault, # this can be TypeVarWithDefault in the reordered example to match the movement of TypeVarWithDefault to the 4th position for readability
      *e: *SimpleTypeVarTuple, # needs a star/unpack here on the right-hand-side for mypy, I think
      # note that mypy appears to have a bug that it cannot yet handle typed varargs after some other typed arguments like Callables preceding it, e.g. https://github.com/python/mypy/issues/21907 , which one trying related examples may encounter
   ): pass

def some_fun_returns_str(a: str, b: bytearray) -> str:
    return 'abc'

def some_bad_param_fun_returns_str(a: int, b: bytearray) -> str:
    return 'abc'

def some_fun_returns_bytes(a: str, b: bytearray) -> bytes:
    return b'abc'

def some_fun_returns_int(a: str, b: bytearray) -> int:
    return 1

overly_generic('a', 1, some_fun_returns_str, 2)
overly_generic('a', 1, some_fun_returns_bytes, 2)

# error: Value of type variable "TypeVarWithConstraints" of "overly_generic" cannot be "int"  [type-var]
# overly_generic[('a', 1, some_fun_returns_int, 2)

# error: Value of type variable "TypeVarWithBound" of "overly_generic" cannot be "str"  [type-var]
# overly_generic('a', '1', some_fun_returns_str, 2)

# If we force the ParamSpec of the Callable argument
# to be the default of SimpleParamSpec
# e.g. `c: Callable[[str, bytearray], TypeVarWithConstraints]`
# then we can see that properly types the arguments to the callable, and we can't pass a function that takes an int and a bytearray, only a str and bytearray:
#
# error: Argument 3 to "overly_generic" has incompatible type "Callable[[int, bytearray], str]"; expected "Callable[[str, bytearray], str]"  [arg-type]
# overly_generic('a', 1, some_bad_param_fun_returns_str, 2) # will fail mypy if SimpleParamSpec replaced with [str, bytearray]

# we can also show that an unpacked tuple (using `*` or `Unpack[...]`) is the expected type for `*e` varargs (like `*args`):
def example_fun_with_typed_varargs(
      *e: *tuple[int, float],
   ): pass

example_fun_with_typed_varargs(1, 1.1) # OK

# error: Argument 1 to "example_fun_with_typed_varargs" has incompatible type "float"; expected "int"  [arg-type]
# example_fun_with_typed_varargs(1.2, 1.1) # mypy rejects

# note that mypy has a bug that it cannot handle typed varargs after some other typed arguments like Callables preceding it, e.g. https://github.com/python/mypy/issues/21907 , which one trying related examples may encounter
# that is not caused by anything particular to the example we are proposing to put here